02-核心机制深度解析
<![CDATA[# 第2章 核心机制深度解析
## 2.1 插件机制总览
Xiuno BBS的插件系统采用**编译时合并**架构，而非WordPress那样的运行时钩子系统。核心思路是：在请求处理时，将源文件与插件的hook代码、overwrite文件合并编译后写入`tmp/`目录缓存，后续请求直接include缓存文件。
**核心优势**: 零运行时开销——编译一次，后续请求直接执行合并后的PHP文件，性能等同于原生代码。
**核心函数**: `_include()` 是整个插件机制的入口，所有需要支持插件的文件都必须通过此函数加载。
## 2.2 Hook（钩子）机制
### 2.2.1 工作原理
Hook机制是面向切面编程(AOP)的实现。系统在源码中预设标记点，插件在`hook/`目录下放置同名文件，编译时系统将插件代码插入到标记位置。
**标记格式**:
| 文件类型 | 标记语法 | 示例 |
| ----- | ----------------------- | -------------------------------------- |
| PHP文件 | `// hook 文件名.php` | `// hook index_start.php` |
| HTM模板 | `<!--{hook 文件名.htm}-->` | `<!--{hook thread_plugin_body.htm}-->` |
### 2.2.2 编译流程
```
源文件 (如 route/index.php)
↓ 读取文件内容
↓ 统一标记格式: <!--{hook xxx}--> → // hook xxx
↓ 正则匹配: // hook xxx
↓ 回调替换: plugin_compile_srcfile_callback()
│ ├─ 扫描所有已启用插件的 hook/ 目录
│ ├─ 找到同名hook文件
│ ├─ 按 hooks_rank 权重排序
│ └─ 读取文件内容，去除 <?php exit; 保护头
↓ 写入 tmp/ 缓存
↓ 返回缓存文件路径，由调用方 include
```
### 2.2.3 Hook点分布
系统自身共有**443个Hook点**，分布如下:
| 模块 | Hook点数量 | 主要模板 |
| ---------- | ------- | -------------------------- |
| thread | 39 | thread.htm (最密集) |
| post\_list | 21 | post\_list.inc.htm |
| forum | 20 | forum.htm |
| index | 15+ | index.htm |
| user | 10+ | user.htm, user\_create.htm |
| my | 10+ | my.htm |
| admin | 97 | 后台各模板 |
| 第三方插件 | 94 | xn\_nav\_2等 |
而插件又可以定义出自己的hook点供自身或其他插件使用。
### 2.2.4 Hook命名规范
通常的格式是: `{页面/模块}_{位置/元素}_{动作}.htm`
但不限于这样的格式。
常用位置关键词:
- `_start`: 页面/功能开始处
- `_end`: 页面/功能结束处
- `_before`: 某元素之前（推荐，位置精确）
- `_after`: 某元素之后（推荐，位置精确）
- `_js`: JS脚本区域
### 2.2.5 Hook权重排序
通过`conf.json`中的`hooks_rank`字段控制多个插件对同一hook点的注入顺序:
```json
{
"hooks_rank": {
"thread_plugin_body.htm": 500,
"post_post_end.php": -10
}
}
```
- **数值越大，越后执行**（排在越后面）
- **负值表示优先执行**（排在越前面）
- **默认权重为0**（未设置hooks\_rank的插件）
### 2.2.6 Hook文件写法
**PHP Hook文件** (如 `hook/thread_start.php`):
```php
<?php exit; // 保护头，防止直接通过URL访问，编译时自动去除；当然，不写的话也是可以的
if ($action == 'favorite') {
$tid = param(2, 0);
// 业务逻辑...
message(0, '操作成功');
}
```
**HTM Hook文件** (如 `hook/index_site_brief_after.htm`):
```html
<div class="card">
<div class="card-body">
<h5>签到</h5>
<p>今日已有 <?= $sign_count; ?> 人签到</p>
</div>
</div>
```
**Model注入Hook** (如 `hook/model_inc_file.php`):
```php
<?php exit;
APP_PATH.'plugin/my_plugin/model/my_model.func.php',
// 注意：这行会被插入到 model.inc.php 的 $include_model_files 数组中
// 末尾必须有逗号！
```
**路由注册Hook** (如 `hook/index_route_case_end.php`):
```php
<?php exit;
case 'mypage':
include _include(APP_PATH.'plugin/my_plugin/route/mypage.php');
break;
```
**语言包Hook** (如 `hook/lang_zh_cn_bbs.php`):
```php
<?php exit;
'我的插件' => '我的插件',
'插件设置' => '插件设置',
```
## 2.3 Overwrite（覆盖）机制
### 2.3.1 工作原理
Overwrite机制允许插件**完全替换**系统文件或其他插件的文件。通过在插件目录下创建与原始文件路径相同的文件来实现。
```
原始文件: view/htm/header.inc.htm
覆盖文件: plugin/my_theme/overwrite/view/htm/header.inc.htm
```
### 2.3.2 覆盖路径映射
覆盖文件的路径 = `plugin/{插件名}/overwrite/` + 原始文件相对于APP\_PATH的路径
示例:
| 原始文件 | 覆盖文件 |
| ----------------------------------- | ------------------------------------------------------------- |
| `view/htm/header.inc.htm` | `plugin/my_theme/overwrite/view/htm/header.inc.htm` |
| `route/index.php` | `plugin/my_plugin/overwrite/route/index.php` |
| `plugin/xn_search/route/search.php` | `plugin/my_theme/overwrite/plugin/xn_search/route/search.php` |
> **重要**: 主题可以覆盖其他插件的文件，实现深度适配。
### 2.3.3 权重排序
多个插件覆盖同一文件时，`overwrites_rank`值最大的胜出:
```json
{
"overwrites_rank": {
"view/htm/header.inc.htm": 100
}
}
```
### 2.3.4 Overwrite后的Hook处理
被overwrite的文件仍然会继续走hook编译流程，即overwrite文件中的`// hook xxx`和`<!--{hook xxx}-->`标记仍然有效。
## 2.4 \_include() 函数详解
`_include()` 是插件系统的核心函数，定义在 `model/plugin.func.php`:
```php
function _include($srcfile) {
global $conf;
$len = strlen(APP_PATH);
$tmpfile = $conf['tmp_path'].substr(str_replace('/', '_', $srcfile), $len);
if(!is_file($tmpfile) || DEBUG > 1) {
// 第一次编译: 处理overwrite + hook
$s = plugin_compile_srcfile($srcfile);
// 处理 <template>/<slot> 机制
$g_include_slot_kv = array();
for($i = 0; $i < 10; $i++) {
$s = preg_replace_callback('#<template\sinclude="(.*?)">(.*?)</template>#is',
'_include_callback_1', $s);
if(strpos($s, '<template') === FALSE) break;
}
file_put_contents_try($tmpfile, $s);
// 第二次编译: 处理slot替换后可能产生的新hook
$s = plugin_compile_srcfile($tmpfile);
file_put_contents_try($tmpfile, $s);
}
return $tmpfile;
}
```
**关键行为**:
1. 将源文件路径转换为tmp缓存路径（`route/index.php` → `tmp/route_index.php`）
2. `DEBUG > 1`时每次请求重新编译，否则使用缓存
3. 编译两次：第一次处理hook注入，第二次处理slot替换后可能产生的新hook
4. 返回编译后的缓存文件路径，由调用方`include`
## 2.5 Template/Slot 机制
类似Vue.js的组件插槽系统，用于模板组合与复用:
**定义Slot** (在模板中):
```html
<slot name="thread_actions" />
```
**填充Slot** (在插件中):
```html
<template include="view/htm/thread.htm">
<slot name="thread_actions">
<button>自定义按钮</button>
</slot>
</template>
```
## 2.6 插件状态管理
### 已启用插件的判定
只有`enable=1`且`installed=1`的插件才会被加载:
```php
function plugin_paths_enabled() {
// ...
if(empty($pconf['enable']) || empty($pconf['installed'])) continue;
// ...
}
```
### 缓存清理
任何插件状态变更（安装/卸载/启用/禁用）都会调用`plugin_clear_tmp_dir()`清空`tmp/`目录，确保下次请求重新编译。
### 插件加载顺序
插件按目录名字母顺序加载，hook注入顺序由`hooks_rank`控制。
]]>